/*
 * Copyright 2002-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.web.context.request;

import java.security.Principal;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Arrays;
import java.util.Enumeration;
import java.util.Iterator;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.TimeZone;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;

import org.springframework.http.HttpMethod;
import org.springframework.http.HttpStatus;
import org.springframework.lang.Nullable;
import org.springframework.util.CollectionUtils;
import org.springframework.util.ObjectUtils;
import org.springframework.util.StringUtils;
import org.springframework.web.util.WebUtils;

/**
 * {@link WebRequest} adapter for an {@link javax.servlet.http.HttpServletRequest}.
 *
 * @author Juergen Hoeller
 * @author Brian Clozel
 * @author Markus Malkusch
 * @since 2.0
 */
public class ServletWebRequest extends ServletRequestAttributes implements NativeWebRequest {

	private static final String ETAG = "ETag";


	/**
	 * 从字面上看, 就是说: 如果从某个时间点算起, 如果文件被修改了....
	 *   1. 如果真的被修改: 那么就开始传输, 服务器返回:200 OK
	 *   2. 如果没有被修改: 那么就无需传输, 服务器返回: 304 Not Modified.
	 *
	 * 用途:
	 *
   *              客户端尝试下载最新版本的文件. 比如网页刷新, 加载大图的时候.
*              很明显: 如果从图片下载以后都没有再被修改, 当然就没必要重新下载了!
	 */
	private static final String IF_MODIFIED_SINCE = "If-Modified-Since";

	/**
	 * 从字面上看, 意思是: 如果从某个时间点算起, 文件没有被修改.....
	 *  1. 如果没有被修改: 则开始`继续'传送文件: 服务器返回: 200 OK
	 *  2. 如果文件被修改: 则不传输, 服务器返回: 412 Precondition failed (预处理错误)
	 *
	 *  用途:
	 * 断点续传(一般会指定Range参数). 要想断点续传, 那么文件就一定不能被修改, 否则就不是同一个文件了, 断续还有啥意义?
	 */
	private static final String IF_UNMODIFIED_SINCE = "If-Unmodified-Since";

	private static final String IF_NONE_MATCH = "If-None-Match";

	private static final String LAST_MODIFIED = "Last-Modified";

	/**
	 * 缓存只针对GET、HEAD
	 */
	private static final List<String> SAFE_METHODS = Arrays.asList("GET", "HEAD");

	/**
	 * Pattern matching ETag multiple field values in headers such as "If-Match", "If-None-Match".
	 * @see <a href="https://tools.ietf.org/html/rfc7232#section-2.3">Section 2.3 of RFC 7232</a>
	 */
	private static final Pattern ETAG_HEADER_VALUE_PATTERN = Pattern.compile("\\*|\\s*((W\\/)?(\"[^\"]*\"))\\s*,?");

	/**
	 * Date formats as specified in the HTTP RFC.
	 * @see <a href="https://tools.ietf.org/html/rfc7231#section-7.1.1.1">Section 7.1.1.1 of RFC 7231</a>
	 */
	private static final String[] DATE_FORMATS = new String[] {
			"EEE, dd MMM yyyy HH:mm:ss zzz",
			"EEE, dd-MMM-yy HH:mm:ss zzz",
			"EEE MMM dd HH:mm:ss yyyy"
	};

	private static final TimeZone GMT = TimeZone.getTimeZone("GMT");

	// 如果文档被修改 ，则 this.notModified 被设置为 true
	// 如果文档未被修改，则 notModified 被设置为 false
	private boolean notModified = false;


	/**
	 * Create a new ServletWebRequest instance for the given request.
	 * @param request current HTTP request
	 */
	public ServletWebRequest(HttpServletRequest request) {
		super(request);
	}

	/**
	 * Create a new ServletWebRequest instance for the given request/response pair.
	 * @param request current HTTP request
	 * @param response current HTTP response (for automatic last-modified handling)
	 */
	public ServletWebRequest(HttpServletRequest request, @Nullable HttpServletResponse response) {
		super(request, response);
	}


	@Override
	public Object getNativeRequest() {
		return getRequest();
	}

	@Override
	public Object getNativeResponse() {
		return getResponse();
	}

	@Override
	public <T> T getNativeRequest(@Nullable Class<T> requiredType) {
		return WebUtils.getNativeRequest(getRequest(), requiredType);
	}

	@Override
	public <T> T getNativeResponse(@Nullable Class<T> requiredType) {
		HttpServletResponse response = getResponse();
		return (response != null ? WebUtils.getNativeResponse(response, requiredType) : null);
	}

	/**
	 * Return the HTTP method of the request.
	 * @since 4.0.2
	 */
	@Nullable
	public HttpMethod getHttpMethod() {
		return HttpMethod.resolve(getRequest().getMethod());
	}

	@Override
	@Nullable
	public String getHeader(String headerName) {
		return getRequest().getHeader(headerName);
	}

	@Override
	@Nullable
	public String[] getHeaderValues(String headerName) {
		String[] headerValues = StringUtils.toStringArray(getRequest().getHeaders(headerName));
		return (!ObjectUtils.isEmpty(headerValues) ? headerValues : null);
	}

	@Override
	public Iterator<String> getHeaderNames() {
		return CollectionUtils.toIterator(getRequest().getHeaderNames());
	}

	@Override
	@Nullable
	public String getParameter(String paramName) {
		return getRequest().getParameter(paramName);
	}

	@Override
	@Nullable
	public String[] getParameterValues(String paramName) {
		return getRequest().getParameterValues(paramName);
	}

	@Override
	public Iterator<String> getParameterNames() {
		return CollectionUtils.toIterator(getRequest().getParameterNames());
	}

	@Override
	public Map<String, String[]> getParameterMap() {
		return getRequest().getParameterMap();
	}

	@Override
	public Locale getLocale() {
		return getRequest().getLocale();
	}

	@Override
	public String getContextPath() {
		return getRequest().getContextPath();
	}

	@Override
	@Nullable
	public String getRemoteUser() {
		return getRequest().getRemoteUser();
	}

	@Override
	@Nullable
	public Principal getUserPrincipal() {
		return getRequest().getUserPrincipal();
	}

	@Override
	public boolean isUserInRole(String role) {
		return getRequest().isUserInRole(role);
	}

	@Override
	public boolean isSecure() {
		return getRequest().isSecure();
	}


	@Override
	public boolean checkNotModified(long lastModifiedTimestamp) {
		return checkNotModified(null, lastModifiedTimestamp);
	}

	@Override
	public boolean checkNotModified(String etag) {
		return checkNotModified(etag, -1);
	}

	/**
	 * 支持HTTP缓存机制强/弱验证器机制，
	 *
	 * 服务器端在缓存资源副本重新验证请求到达时执行验证过程。该验证过程主要依赖如下头部信息 :
	 * 强验证器头部 : ETag/If-None-Match
	 * 		ETag 响应头部
	 * 			语义 : 表示资源是否变化的一个标志字符串；对浏览器来讲是一个黑盒子，浏览器不清楚它的值是什么意思也无从猜测。
	 * 		If-None-Match 请求头部
	 * 			语义 : 是否不能匹配上某个资源。如果缓存资源部分对应资源正本已经变化，则新的资源正本一定会产生一个不同的ETag值，从而使之前的ETag变成无法匹配。
	 * 		如果对某个资源响应ETag头部被使用，浏览器验证该资源时可以使用此头部，使用ETag的值向服务器询问该资源是否真正过期。
	 * 		服务器会通过ETag值匹配判断缓存资源副本是否过期。
	 *弱验证器头部 : Last-Modified/If-Modified-Since
	 *		Last-Modified 响应头部
	 * 			语义 : 资源最近修改时间。
	 * 		If-Modified-Since 请求头部
	 * 		语义 : 表示资源在某个时间之后是否被修改。
	 * 		浏览器验证该资源时可以使用此头部，使用Last-Modified的值向服务器询问该资源是否真正过期。
	 * 		服务器端会使用Last-Modified值和服务器端资源最近一次被修改的时间判断缓存资源副本是否过期。

	 *
	 *
	 *
	 *
	 *
	 *    2.当接收方是原始服务器，如果不存在If-Match，并且存在
	 *        If-Unmodified-Since，则评估If-Unmodified-Since
	 *        前提：
	 *
	 *        *如果为true，则继续执行步骤3
	 *
	 *        *如果为
	 *           否，则响应412（前提失败），除非可以确定状态更改请求已经
	 *           成功（请参阅第3.4节）
	 *
	 *    。3.如果存在If-None-Match，则评估If-None-Match
	 *        前提：
	 *
	 *        *如果为true，则继续执行步骤5
	 *
	 *        *如果GET / HEAD为false，则响应304（未修改）
	 *
	 *        *如果对于其他方法为false，则响应412（前提条件失败）
	 *
	 *    。4.当该方法为GET或HEAD，If-None-Match不存在且
	 *        If-Modified-Since存在时，评估If-Modified-Since
	 *        前提条件：
	 *
	 *        *如果为true，则继续执行步骤5
	 *
	 *        *如果为false，则响应304（未修改）
	 *
	 *    5.当该方法为GET且同时存在Range和If-Range时，
	 *        评估If-Range前提条件：
	 *
	 *        *如果验证器匹配且Range规范
	 *           适用于所选表示，请响应206
	 *           （部分内容）[ RFC7233 ]
	 *
	 *    6。否则，
	 *
	 *        *满足所有条件，因此请执行请求的操作并
	 *           根据其成功或失败进行响应。
	 */
	@Override
	public boolean checkNotModified(@Nullable String etag, long lastModifiedTimestamp) {
		HttpServletResponse response = getResponse();
		// 这个地方说明状态不是200不会缓存
		if (this.notModified || (response != null && HttpStatus.OK.value() != response.getStatus())) {
			return this.notModified;
		}

		// Evaluate conditions in order of precedence.
		// See https://tools.ietf.org/html/rfc7232#section-6

		//1、 获取请求头部 If-Unmodified-Since :
		// 告知服务器,指定的请求资源只有在字段值内指定的时间之后(未)发生更新的情况下才能处理请求。
		// 如果在指定日期时间后发生更新,则以状态码 412 Precondition Failed 作为响应返回
		if (validateIfUnmodifiedSince(lastModifiedTimestamp)) {
			if (this.notModified && response != null) {
				response.setStatus(HttpStatus.PRECONDITION_FAILED.value());
			}
			return this.notModified;
		}

		//2、首先尝试检测是否是 Etag/If-None-Match 强验证器机制并尝试应用，
		//否则再检测是否是 Last-Modified/If-Modified-Since 弱验证器机制并尝试应用
		boolean validated = validateIfNoneMatch(etag);
		if (!validated) {
			// 不是强验证器机制,再检测是否是 Last-Modified/If-Modified-Since 弱验证器机制并尝试应用
			validateIfModifiedSince(lastModifiedTimestamp);
		}


		// 更新响应对象
		if (response != null) {
			// 这个地方说明缓存只处理get或者head请求方式
			boolean isHttpGetOrHead = SAFE_METHODS.contains(getRequest().getMethod());

			if (this.notModified) {
				// 如果 资源修改了, 则根据请求HTTP方式决定响应 304 还是 412
				response.setStatus(isHttpGetOrHead ?
						HttpStatus.NOT_MODIFIED.value() : HttpStatus.PRECONDITION_FAILED.value());
			}

			// 资源没有修改，并且 HTTP 请求方法为 GET 或者 HEAD,
			// 此时设置响应头部 Last-Modified, 或者 ETag
			if (isHttpGetOrHead) {
				if (lastModifiedTimestamp > 0 && parseDateValue(response.getHeader(LAST_MODIFIED)) == -1) {
					response.setDateHeader(LAST_MODIFIED, lastModifiedTimestamp);
				}

				if (StringUtils.hasLength(etag) && response.getHeader(ETAG) == null) {
					response.setHeader(ETAG, padEtagIfNecessary(etag));
				}
			}
		}

		return this.notModified;
	}


	/**
	 * 返回 false 表示没有检测到请求头部 If-Unmodified-Since 或者  lastModifiedTimestamp<0,
	 * 返回 true 表示检测到请求头部 If-Unmodified-Since 并结合 lastModifiedTimestamp(>0)使用
	 */
	private boolean validateIfUnmodifiedSince(long lastModifiedTimestamp) {
		if (lastModifiedTimestamp < 0) {
			// 文档最近一次更新时间为 -1, 返回 false
			return false;
		}

		long ifUnmodifiedSince = parseDateHeader(IF_UNMODIFIED_SINCE);
		if (ifUnmodifiedSince == -1) {
			// 请求头部不带 If-Unmodified-Since , 返回 false
			return false;
		}

		// We will perform this validation...
		// 小于 true 文件修改      大于 false 文件没有修改
		this.notModified = (ifUnmodifiedSince < (lastModifiedTimestamp / 1000 * 1000));
		return true;
	}


	/**
	 *如果服务端数据实体发生变化的话，其 etag 也会发生变化，该方法获取请求头部 If-None-Match，
	 * 它记录了客户端首次访问该地址所获取的服务端数据实体的 etag，该方法通过比较这两个 etag
	 * 确定客户端的缓存副本和服务器端数据实体当前版本是否一致
	 *
	 * @param etag    是服务端数据实体的唯一标识,
	 * @return  true 表明 Etag/If-None-Match 强验证器机制被应用，
	 * false 不需要再执行 Last-Modified/If-Modified-Since 弱验证器机制
	 */
	private boolean validateIfNoneMatch(@Nullable String etag) {
		if (!StringUtils.hasLength(etag)) {

			return false;
		}
		Enumeration<String> ifNoneMatch;
		try {
			ifNoneMatch = getRequest().getHeaders(IF_NONE_MATCH);
		}
		catch (IllegalArgumentException ex) {
			return false;
		}
		if (!ifNoneMatch.hasMoreElements()) {
			return false;
		}

		// We will perform this validation...
		etag = padEtagIfNecessary(etag);
		if (etag.startsWith("W/")) {
			etag = etag.substring(2);
		}
		while (ifNoneMatch.hasMoreElements()) {
			String clientETags = ifNoneMatch.nextElement();
			Matcher etagMatcher = ETAG_HEADER_VALUE_PATTERN.matcher(clientETags);
			// Compare weak/strong ETags as per https://tools.ietf.org/html/rfc7232#section-2.3
			while (etagMatcher.find()) {
				if (StringUtils.hasLength(etagMatcher.group()) && etag.equals(etagMatcher.group(3))) {
					this.notModified = true;
					break;
				}
			}
		}

		return true;
	}

	private String padEtagIfNecessary(String etag) {
		if (!StringUtils.hasLength(etag)) {
			return etag;
		}
		if ((etag.startsWith("\"") || etag.startsWith("W/\"")) && etag.endsWith("\"")) {
			return etag;
		}
		return "\"" + etag + "\"";
	}


	private boolean validateIfModifiedSince(long lastModifiedTimestamp) {
		if (lastModifiedTimestamp < 0) {
			return false;
		}
		// 获取日期类型请求头部 If-Unmodified-Since :
		long ifModifiedSince = parseDateHeader(IF_MODIFIED_SINCE);
		if (ifModifiedSince == -1) {
			return false;
		}

		// We will perform this validation...
		//  判断文件是否修改
		this.notModified = ifModifiedSince >= (lastModifiedTimestamp / 1000 * 1000);

		return true;
	}

	public boolean isNotModified() {
		return this.notModified;
	}

	private long parseDateHeader(String headerName) {
		long dateValue = -1;
		try {
			dateValue = getRequest().getDateHeader(headerName);
		}
		catch (IllegalArgumentException ex) {
			String headerValue = getHeader(headerName);
			// Possibly an IE 10 style value: "Wed, 09 Apr 2014 09:57:42 GMT; length=13774"
			if (headerValue != null) {
				int separatorIndex = headerValue.indexOf(';');
				if (separatorIndex != -1) {
					String datePart = headerValue.substring(0, separatorIndex);
					dateValue = parseDateValue(datePart);
				}
			}
		}
		return dateValue;
	}

	private long parseDateValue(@Nullable String headerValue) {
		if (headerValue == null) {
			// No header value sent at all
			return -1;
		}
		if (headerValue.length() >= 3) {
			// Short "0" or "-1" like values are never valid HTTP date headers...
			// Let's only bother with SimpleDateFormat parsing for long enough values.
			for (String dateFormat : DATE_FORMATS) {
				SimpleDateFormat simpleDateFormat = new SimpleDateFormat(dateFormat, Locale.US);
				simpleDateFormat.setTimeZone(GMT);
				try {
					return simpleDateFormat.parse(headerValue).getTime();
				}
				catch (ParseException ex) {
					// ignore
				}
			}
		}
		return -1;
	}

	@Override
	public String getDescription(boolean includeClientInfo) {
		HttpServletRequest request = getRequest();
		StringBuilder sb = new StringBuilder();
		sb.append("uri=").append(request.getRequestURI());
		if (includeClientInfo) {
			String client = request.getRemoteAddr();
			if (StringUtils.hasLength(client)) {
				sb.append(";client=").append(client);
			}
			HttpSession session = request.getSession(false);
			if (session != null) {
				sb.append(";session=").append(session.getId());
			}
			String user = request.getRemoteUser();
			if (StringUtils.hasLength(user)) {
				sb.append(";user=").append(user);
			}
		}
		return sb.toString();
	}


	@Override
	public String toString() {
		return "ServletWebRequest: " + getDescription(true);
	}

}
